Skip to content

Implement --log CLI argument with rx and tx options#84

Open
slook wants to merge 2 commits intosoulfind-dev:masterfrom
slook:log-arguments
Open

Implement --log CLI argument with rx and tx options#84
slook wants to merge 2 commits intosoulfind-dev:masterfrom
slook:log-arguments

Conversation

@slook
Copy link
Copy Markdown
Member

@slook slook commented Mar 30, 2026

Enables additional logging, and takes an optional list of log categories to enable, with filtering by message code number.

--log categories:

  • conn: Connections
  • db: Database operations
  • msg: Includes both r and t
  • r: Received network messages
  • rx: Received network messages with hexadecimal bytes
  • t: Transmitted network messages
  • tx: Transmitted network messages with hexadecimal bytes
  • x: Includes both rx and tx
  • 1 .. 1003: Filter by message code

Based on PR #81 by @jpdillingham and PR #82 by @mathiascode

@slook slook force-pushed the log-arguments branch 2 times, most recently from 73b64da to 64a8fa8 Compare March 30, 2026 22:26
@mathiascode
Copy link
Copy Markdown
Member

Alright, maybe this could be an option. Just remember that we're sacrificing extensibility, so don't expect me to consider any future requests regarding advanced filtering or categories.

Do we need combined categories like msg and x if we have a flat list? In my opinion they mostly cause confusion, at least in your msg rx example. Why not go with just rx t?

@slook
Copy link
Copy Markdown
Member Author

slook commented Mar 31, 2026

we're sacrificing extensibility ... regarding advanced filtering or categories

This is already quite a flexible arrangement, any more advanced filtering than what's done here would require the parameters to be in a very specific order which would make the command line interface too difficult to understand. The only other useful filtering that could be added as options of the --log argument are:

  • Code ranges:
    • Numeric parameters containing a - hypen in the middle, or;
    • Numeric parameters seperated by .. two dots in the middle.
  • Users:
    • Alphanumeric parameters that are not log categories, or;
    • Alphanumeric parameters that are prefixed with an @ character.
    • Only usernames that contain spaces or , commas will need "quoting" in the shell (requiring sight modification to the cli module to callback an array of values instead of a concatenated string).
  • Silent/Quiet:
    • Turn logging off completely, only showing that the server is listening, or;
    • Write only a basic one-line status counter, such as to indicate the number of connected users.

If desired at a later time, those features could be added into the default: case in enable_log_category(), but this goes beyond the requested feature so beyond the scope of this PR.

Do we need combined categories like msg and x if we have a flat list? ... they mostly cause confusion

Are you suggesting that it would be less confusing if the presence of an x character enabled hexadecimal mode for whichever direction is specified, such that for instance rx would be equivalent to r x for showing only received bytes, and not having x enable both directions unless neither r nor t were specified?

Enables additional logging, and takes an optional list of log
categories to enable, with filtering by message code number.

Co-authored-by: Mat <mail@mathias.is>
Adds proper support for shell quoted values (like "file name.db") with strict rejection of misplaced or unexpected inputs.
@slook
Copy link
Copy Markdown
Member Author

slook commented Apr 1, 2026

I pushed a change to the cli module to callback an array of values instead of a concatenated string. The advantage is native support for shell quoted strings for proper rejection of misplaced or unexpected inputs.

This constrains an option to take only its correct amount of values (i.e. zero or one, except for options with defaults) which makes the argument parser output more helpful syntax exception messages...

$ soulfind --datebass
soulfind: Unknown option '--datebass'

$ soulfind --database
database: Missing value for <path>

$ soulfind --database long stupid name.db log rx
database: Unexpected value 'stupid'

$ soulfind --database "long stupid name.db" log rx
database: Unexpected value 'log'

$ soulfind --database "long stupid name.db" --log rx "long cat" 1 2 34
Available log categories: 'conn' 'db' 'msg' 'r' 'rx' 't' 'tx' 'x' '0..4294967295'
log: Unknown log category 'long cat'

... and this eliminates the need for any custom splitting to select log_categories.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants